Eclipse Platform
Pre-release 3.0

org.eclipse.core.runtime
Interface IPlatform


public interface IPlatform

The central class of the Eclipse Platform Runtime. This class cannot be instantiated or subclassed by clients; all functionality is provided by static methods. Features include:

The platform is in one of two states, running or not running, at all times. The only ways to start the platform running, or to shut it down, are on the bootstrap BootLoader class. Code in plug-ins will only observe the platform in the running state. The platform cannot be shutdown from inside (code in plug-ins have no access to BootLoader).

Note: This is an early access API to the new OSGI-based Eclipse 3.0 Platform Runtime. Because the APIs for the new runtime have not yet been fully stabilized, they should only be used by clients needing to take particular advantage of new OSGI-specific functionality, and only then with the understanding that these APIs may well change in incompatible ways until they reach their finished, stable form (post-3.0).

Since:
3.0

Field Summary
static int FAILED_DELETE_METADATA
          Status code constant (value 6) indicating the platform could not delete some of its metadata.
static int FAILED_READ_METADATA
          Status code constant (value 4) indicating the platform could not read some of its metadata.
static int FAILED_WRITE_METADATA
          Status code constant (value 5) indicating the platform could not write some of its metadata.
static int INTERNAL_ERROR
          Status code constant (value 3) indicating an error internal to the platform has occurred.
static int PARSE_PROBLEM
          Status code constant (value 1) indicating a problem in a plug-in manifest (plugin.xml) file.
static String PI_RUNTIME
          The unique identifier constant (value "org.eclipse.core.runtime") of the Core Runtime plug-in.
static String PI_RUNTIME_COMPATIBILITY
           
static int PLUGIN_ERROR
          Status code constant (value 2) indicating an error occurred while running a plug-in.
static String PREF_PLATFORM_PERFORMANCE
          Name of a preference for configuring the performance level for this system.
static String PT_APPLICATIONS
          The simple identifier constant (value "applications") of the extension point of the Core Runtime plug-in where plug-ins declare the existence of runnable applications.
static String PT_SHUTDOWN_HOOK
           
static String PT_URLHANDLERS
           
 
Method Summary
 void addAuthorizationInfo(URL serverUrl, String realm, String authScheme, Map info)
          Adds the given authorization information to the keyring.
 void addLogListener(ILogListener listener)
          Adds the given log listener to the notification list of the platform.
 void addProtectionSpace(URL resourceUrl, String realm)
          Adds the specified resource to the protection space specified by the given realm.
 URL asLocalURL(URL url)
          Returns a URL which is the local equivalent of the supplied URL.
 void endSplash()
          Takes down the splash screen if one was put up.
 URL find(org.osgi.framework.Bundle b, IPath path)
           
 URL find(org.osgi.framework.Bundle b, IPath path, Map override)
           
 void flushAuthorizationInfo(URL serverUrl, String realm, String authScheme)
          Removes the authorization information for the specified protection space and given authorization scheme.
 IAdapterManager getAdapterManager()
          Returns the adapter manager used for extending IAdaptable objects.
 String[] getAllArgs()
          Returns all command line arguments specified when the running framework was started.
 String[] getApplicationArgs()
          Returns the arguments not consumed by the framework implementation itself.
 Map getAuthorizationInfo(URL serverUrl, String realm, String authScheme)
          Returns the authorization information for the specified protection space and given authorization scheme.
 IPath getConfigurationMetadataLocation()
          Returns the location in the filesystem of the configuration information used to run this instance of Eclipse.
 String[] getFrameworkArgs()
          Returns the arguments consumed by the framework implementation itself.
 URL getInstallURL()
          Returns URL at which the Platform runtime executables and libraries are installed.
 IJobManager getJobManager()
          Returns the platform job manager.
 IPath getLocation()
          Returns the location of the platform working directory.
 ILog getLog(org.osgi.framework.Bundle bundle)
          Returns the log for the given bundle.
 IPath getLogFileLocation()
          Returns the location of the platform log file.
 String getNL()
          Returns the string name of the current locale for use in finding files whose path starts with $nl$.
 String getOS()
          Returns the string name of the current operating system for use in finding files whose path starts with $os$.
 String getOSArch()
          Returns the string name of the current system architecture.
 String getProtectionSpace(URL resourceUrl)
          Returns the protection space (realm) for the specified resource, or null if the realm is unknown.
 ResourceBundle getResourceBundle(org.osgi.framework.Bundle bundle)
          Returns the given bundle's resource bundle for the current locale.
 String getResourceString(org.osgi.framework.Bundle bundle, String value)
          Returns a resource string corresponding to the given argument value.
 String getResourceString(org.osgi.framework.Bundle bundle, String value, ResourceBundle resourceBundle)
          Returns a resource string corresponding to the given argument value and bundle.
 IPath getStateLocation(org.osgi.framework.Bundle bundle)
          Returns the location in the local file system of the plug-in state area for the given bundle.
 String getWS()
          Returns the string name of the current window system for use in finding files whose path starts with $ws$.
 InputStream openStream(org.osgi.framework.Bundle b, IPath file)
           
 InputStream openStream(org.osgi.framework.Bundle b, IPath file, boolean localized)
          Returns an input stream for the specified file.
 void removeLogListener(ILogListener listener)
          Removes the indicated (identical) log listener from the notification list of the platform.
 URL resolve(URL url)
          Returns a URL which is the resolved equivalent of the supplied URL.
 void run(ISafeRunnable code)
          Runs the given runnable in a protected mode.
 

Field Detail

PREF_PLATFORM_PERFORMANCE

public static final String PREF_PLATFORM_PERFORMANCE
Name of a preference for configuring the performance level for this system.

This value can be used by all components to customize features to suit the speed of the user's machine. The platform job manager uses this value to make scheduling decisions about background jobs.

The preference value must be an integer between the constant values MIN_PERFORMANCE and MAX_PERFORMANCE

Since:
3.0
See Also:
#MIN_PERFORMANCE, #MAX_PERFORMANCE, Constant Field Values

PI_RUNTIME

public static final String PI_RUNTIME
The unique identifier constant (value "org.eclipse.core.runtime") of the Core Runtime plug-in.

See Also:
Constant Field Values

PI_RUNTIME_COMPATIBILITY

public static final String PI_RUNTIME_COMPATIBILITY
See Also:
Constant Field Values

PT_APPLICATIONS

public static final String PT_APPLICATIONS
The simple identifier constant (value "applications") of the extension point of the Core Runtime plug-in where plug-ins declare the existence of runnable applications. A plug-in may define any number of applications; however, the platform is only capable of running one application at a time.

See Also:
org.eclipse.core.boot.BootLoader#run, Constant Field Values

PT_URLHANDLERS

public static final String PT_URLHANDLERS
See Also:
Constant Field Values

PT_SHUTDOWN_HOOK

public static final String PT_SHUTDOWN_HOOK
See Also:
Constant Field Values

PARSE_PROBLEM

public static final int PARSE_PROBLEM
Status code constant (value 1) indicating a problem in a plug-in manifest (plugin.xml) file.

See Also:
Constant Field Values

PLUGIN_ERROR

public static final int PLUGIN_ERROR
Status code constant (value 2) indicating an error occurred while running a plug-in.

See Also:
Constant Field Values

INTERNAL_ERROR

public static final int INTERNAL_ERROR
Status code constant (value 3) indicating an error internal to the platform has occurred.

See Also:
Constant Field Values

FAILED_READ_METADATA

public static final int FAILED_READ_METADATA
Status code constant (value 4) indicating the platform could not read some of its metadata.

See Also:
Constant Field Values

FAILED_WRITE_METADATA

public static final int FAILED_WRITE_METADATA
Status code constant (value 5) indicating the platform could not write some of its metadata.

See Also:
Constant Field Values

FAILED_DELETE_METADATA

public static final int FAILED_DELETE_METADATA
Status code constant (value 6) indicating the platform could not delete some of its metadata.

See Also:
Constant Field Values
Method Detail

addAuthorizationInfo

public void addAuthorizationInfo(URL serverUrl,
                                 String realm,
                                 String authScheme,
                                 Map info)
                          throws CoreException
Adds the given authorization information to the keyring. The information is relevant for the specified protection space and the given authorization scheme. The protection space is defined by the combination of the given server URL and realm. The authorization scheme determines what the authorization information contains and how it should be used. The authorization information is a Map of String to String and typically contains information such as usernames and passwords.

Parameters:
serverUrl - the URL identifying the server for this authorization information. For example, "http://www.example.com/".
realm - the subsection of the given server to which this authorization information applies. For example, "realm1@example.com" or "" for no realm.
authScheme - the scheme for which this authorization information applies. For example, "Basic" or "" for no authorization scheme
info - a Map containing authorization information such as usernames and passwords (key type : String, value type : String)
Throws:
CoreException - if there are problems setting the authorization information. Reasons include:
  • The keyring could not be saved.

addLogListener

public void addLogListener(ILogListener listener)
Adds the given log listener to the notification list of the platform.

Once registered, a listener starts receiving notification as entries are added to plug-in logs via ILog.log(). The listener continues to receive notifications until it is replaced or removed.

Parameters:
listener - the listener to register
See Also:
ILog.addLogListener(org.eclipse.core.runtime.ILogListener), removeLogListener(org.eclipse.core.runtime.ILogListener)

addProtectionSpace

public void addProtectionSpace(URL resourceUrl,
                               String realm)
                        throws CoreException
Adds the specified resource to the protection space specified by the given realm. All targets at or deeper than the depth of the last symbolic element in the path of the given resource URL are assumed to be in the same protection space.

Parameters:
resourceUrl - the URL identifying the resources to be added to the specified protection space. For example, "http://www.example.com/folder/".
realm - the name of the protection space. For example, "realm1@example.com"
Throws:
CoreException - if there are problems setting the authorization information. Reasons include:
  • The keyring could not be saved.

asLocalURL

public URL asLocalURL(URL url)
               throws IOException
Returns a URL which is the local equivalent of the supplied URL. This method is expected to be used with plug-in-relative URLs returned by IPluginDescriptor. If the specified URL is not a plug-in-relative URL, it is returned asis. If the specified URL is a plug-in-relative URL of a file (incl. .jar archive), it is returned as a locally-accessible URL using "file:" or "jar:file:" protocol (caching the file locally, if required). If the specified URL is a plug-in-relative URL of a directory, an exception is thrown.

Parameters:
url - original plug-in-relative URL.
Returns:
the resolved URL
Throws:
IOException - if unable to resolve URL
See Also:
resolve(java.net.URL), IPluginDescriptor.getInstallURL()

flushAuthorizationInfo

public void flushAuthorizationInfo(URL serverUrl,
                                   String realm,
                                   String authScheme)
                            throws CoreException
Removes the authorization information for the specified protection space and given authorization scheme. The protection space is defined by the given server URL and realm.

Parameters:
serverUrl - the URL identifying the server to remove the authorization information for. For example, "http://www.example.com/".
realm - the subsection of the given server to remove the authorization information for. For example, "realm1@example.com" or "" for no realm.
authScheme - the scheme for which the authorization information to remove applies. For example, "Basic" or "" for no authorization scheme.
Throws:
CoreException - if there are problems removing the authorization information. Reasons include:
  • The keyring could not be saved.

getAdapterManager

public IAdapterManager getAdapterManager()
Returns the adapter manager used for extending IAdaptable objects.

Returns:
the adapter manager for this platform
See Also:
IAdapterManager

getAuthorizationInfo

public Map getAuthorizationInfo(URL serverUrl,
                                String realm,
                                String authScheme)
Returns the authorization information for the specified protection space and given authorization scheme. The protection space is defined by the given server URL and realm. Returns null if no such information exists.

Parameters:
serverUrl - the URL identifying the server for the authorization information. For example, "http://www.example.com/".
realm - the subsection of the given server to which the authorization information applies. For example, "realm1@example.com" or "" for no realm.
authScheme - the scheme for which the authorization information applies. For example, "Basic" or "" for no authorization scheme
Returns:
the authorization information for the specified protection space and given authorization scheme, or null if no such information exists

getLocation

public IPath getLocation()
Returns the location of the platform working directory. This corresponds to the -data command line argument if present or, if not, the current working directory when the platform was started.

Returns:
the location of the platform

getLogFileLocation

public IPath getLogFileLocation()
Returns the location of the platform log file. This file may contain information about errors that have previously occurred during this invocation of the Platform. Note: it is very important that users of this method do not leave the log file open for extended periods of time. Doing so may prevent others from writing to the log file, which could result in important error messages being lost. It is strongly recommended that clients wanting to read the log file for extended periods should copy the log file contents elsewhere, and immediately close the original file.

Returns:
the path of the log file on disk.

getProtectionSpace

public String getProtectionSpace(URL resourceUrl)
Returns the protection space (realm) for the specified resource, or null if the realm is unknown.

Parameters:
resourceUrl - the URL of the resource whose protection space is returned. For example, "http://www.example.com/folder/".
Returns:
the protection space (realm) for the specified resource, or null if the realm is unknown

removeLogListener

public void removeLogListener(ILogListener listener)
Removes the indicated (identical) log listener from the notification list of the platform. If no such listener exists, no action is taken.

Parameters:
listener - the listener to deregister
See Also:
ILog.removeLogListener(org.eclipse.core.runtime.ILogListener), addLogListener(org.eclipse.core.runtime.ILogListener)

resolve

public URL resolve(URL url)
            throws IOException
Returns a URL which is the resolved equivalent of the supplied URL. This method is expected to be used with plug-in-relative URLs returned by IPluginDescriptor. If the specified URL is not a plug-in-relative URL, it is returned as is. If the specified URL is a plug-in-relative URL, it is resolved to a URL using the actual URL protocol (eg. file, http, etc)

Parameters:
url - original plug-in-relative URL.
Returns:
the resolved URL
Throws:
IOException - if unable to resolve URL
See Also:
asLocalURL(java.net.URL), IPluginDescriptor.getInstallURL()

run

public void run(ISafeRunnable code)
Runs the given runnable in a protected mode. Exceptions thrown in the runnable are logged and passed to the runnable's exception handler. Such exceptions are not rethrown by this method.

Parameters:
code - the runnable to run

getLog

public ILog getLog(org.osgi.framework.Bundle bundle)
Returns the log for the given bundle. If no such log exists, one is created.

Returns:
the log for the given bundle

getJobManager

public IJobManager getJobManager()
Returns the platform job manager.

Returns:
the job manager

getInstallURL

public URL getInstallURL()
Returns URL at which the Platform runtime executables and libraries are installed. The returned value is distinct from the location of any given platform's data.

Returns:
the URL indicating where the platform runtime is installed.

getConfigurationMetadataLocation

public IPath getConfigurationMetadataLocation()
Returns the location in the filesystem of the configuration information used to run this instance of Eclipse. The configuration area typically contains the list of plug-ins available for use, various user setttings (those shared across different instances of the same configuration) and any other such data needed by plug-ins.

Returns:
the path indicating the directory containing the configuration metadata for this running Eclipse.

endSplash

public void endSplash()
Takes down the splash screen if one was put up.


find

public URL find(org.osgi.framework.Bundle b,
                IPath path)

find

public URL find(org.osgi.framework.Bundle b,
                IPath path,
                Map override)

openStream

public InputStream openStream(org.osgi.framework.Bundle b,
                              IPath file)
                       throws IOException
Throws:
IOException

openStream

public InputStream openStream(org.osgi.framework.Bundle b,
                              IPath file,
                              boolean localized)
                       throws IOException
Returns an input stream for the specified file. The file path must be specified relative to this plug-in's installation location. Optionally, the platform searches for the correct localized version of the specified file using the users current locale, and Java naming convention for localized resource files (locale suffix appended to the specified file extension).

The caller must close the returned stream when done.

Parameters:
file - path relative to plug-in installation location
localized - true for the localized version of the file, and false for the file exactly as specified
Returns:
an input stream
Throws:
IOException

getStateLocation

public IPath getStateLocation(org.osgi.framework.Bundle bundle)
Returns the location in the local file system of the plug-in state area for the given bundle. If the plug-in state area did not exist prior to this call, it is created.

The plug-in state area is a file directory within the platform's metadata area where a plug-in is free to create files. The content and structure of this area is defined by the plug-in, and the particular plug-in is solely responsible for any files it puts there. It is recommended for plug-in preference settings and other configuration parameters.

Parameters:
bundle - the bundle whose state location if returned
Returns:
a local file system path
Since:
3.0

getResourceBundle

public ResourceBundle getResourceBundle(org.osgi.framework.Bundle bundle)
                                 throws MissingResourceException
Returns the given bundle's resource bundle for the current locale.

The resource bundle is stored as the plugin.properties file in the plug-in install directory, and contains any translatable strings used in the plug-in manifest file (plugin.xml) along with other resource strings used by the plug-in implementation.

Returns:
the resource bundle
Throws:
MissingResourceException - if the resource bundle was not found
Since:
3.0

getResourceString

public String getResourceString(org.osgi.framework.Bundle bundle,
                                String value)
Returns a resource string corresponding to the given argument value. If the argument value specifies a resource key, the string is looked up in the default resource bundle. If the argument does not specify a valid key, the argument itself is returned as the resource string. The key lookup is performed in the plugin.properties resource bundle. If a resource string corresponding to the key is not found in the resource bundle the key value, or any default text following the key in the argument value is returned as the resource string. A key is identified as a string begining with the "%" character. Note, that the "%" character is stripped off prior to lookup in the resource bundle.

Equivalent to getResourceString(value, getResourceBundle())

Parameters:
value - the value
Returns:
the resource string
See Also:
getResourceBundle(org.osgi.framework.Bundle)

getResourceString

public String getResourceString(org.osgi.framework.Bundle bundle,
                                String value,
                                ResourceBundle resourceBundle)
Returns a resource string corresponding to the given argument value and bundle. If the argument value specifies a resource key, the string is looked up in the given resource bundle. If the argument does not specify a valid key, the argument itself is returned as the resource string. The key lookup is performed against the specified resource bundle. If a resource string corresponding to the key is not found in the resource bundle the key value, or any default text following the key in the argument value is returned as the resource string. A key is identified as a string begining with the "%" character. Note that the "%" character is stripped off prior to lookup in the resource bundle.

For example, assume resource bundle plugin.properties contains name = Project Name

     getResourceString("Hello World") returns "Hello World"
     getResourceString("%name") returns "Project Name"
     getResourceString("%name Hello World") returns "Project Name"
     getResourceString("%abcd Hello World") returns "Hello World"
     getResourceString("%abcd") returns "%abcd"
     getResourceString("%%name") returns "%name"
 

Parameters:
value - the value
bundle - the resource bundle
Returns:
the resource string
See Also:
getResourceBundle(org.osgi.framework.Bundle)

getOSArch

public String getOSArch()
Returns the string name of the current system architecture. The value is a user-defined string if the architecture is specified on the command line, otherwise it is the value returned by java.lang.System.getProperty("os.arch").

Returns:
the string name of the current system architecture

getNL

public String getNL()
Returns the string name of the current locale for use in finding files whose path starts with $nl$.

Returns:
the string name of the current locale

getOS

public String getOS()
Returns the string name of the current operating system for use in finding files whose path starts with $os$. OS_UNKNOWN is returned if the operating system cannot be determined. The value may indicate one of the operating systems known to the platform (as specified in knownOSValues) or a user-defined string if the operating system name is specified on the command line.

Returns:
the string name of the current operating system
See Also:
#knownOSValues

getWS

public String getWS()
Returns the string name of the current window system for use in finding files whose path starts with $ws$. null is returned if the window system cannot be determined.

Returns:
the string name of the current window system or null

getAllArgs

public String[] getAllArgs()
Returns all command line arguments specified when the running framework was started.

Returns:
the array of command line arguments.

getFrameworkArgs

public String[] getFrameworkArgs()
Returns the arguments consumed by the framework implementation itself. Which arguments are consumed is implementation specific.

Returns:
the array of command line arguments consumed by the framework.

getApplicationArgs

public String[] getApplicationArgs()
Returns the arguments not consumed by the framework implementation itself. Which arguments are consumed is implementation specific. These arguments are available for use by the application.

Returns:
the array of command line arguments not consumed by the framework.

Eclipse Platform
Pre-release 3.0

Copyright (c) IBM Corp. and others 2000, 2003. All Rights Reserved.